Framework for things with the name 'document'
Framework for Documents
The framework identifies these four modes (or types) of documents, each catering to different user needs and serving different purposes. It emphasizes the importance of explicitly structuring technical documents around these four types and separating them from each other. In other words, what we call documentation is not just one thing, but four. Understanding the meaning of this and how these four different types function can greatly improve most documents.
The framework divides documentation into two knowledge axes: theory/practice and learning/application. It poses the question of "What direction?" https://gyazo.com/527bc91aee678cddb4a9a162b9ddb5bb and explains the learning-oriented phase, task-oriented phase, information-oriented phase, and explanation-oriented phase.
Tutorials are designed to help beginners achieve the basic capabilities of a product and be able to use it for their purposes. The language used in tutorials should be concrete and specific, focusing on providing step-by-step instructions and clear expectations for learners. The teacher's obligation is to guide the students, and the students' responsibility is to follow the instructions faithfully Students are not responsible for learning, understanding, or memorizing. The only obligation of the learner in this agreement is to do things as instructed. It is important to resist the temptation to introduce abstraction and keep the language and instructions practical and specific. How-to Guides provide instructions for solving specific problems and are goal-oriented. Unlike tutorials, they don't need to take the reader from the beginning to the end of a story. They focus on providing a starting point for users who already know how to reach it and simply provide the conclusion that answers the actual question or problem. It is important to stick to the practical goals of the guide and avoid adding unnecessary explanations that distract the user. When writing a How-to Guide, it is important to choose a title that accurately reflects what the guide demonstrates. The title should clearly indicate the specific action or problem being addressed. The language used in the guide should provide clear instructions and conditional statements, with links to more detailed explanations if necessary. Technical Reference guides provide technical descriptions and instructions for operating a machine or software. They are information-oriented and focus on explaining the software itself (APIs, classes, functions, etc.) and how to use it. The reference guide aims to provide accurate, up-to-date, and comprehensive information, similar to looking up information in an encyclopedia. It should not include instructions on how to perform a task or suggestions on how to use the software for specific purposes You can't expect to find suggestions on how to cook with it. Explanations are discussions that clarify and make a specific topic clear. They are understanding-oriented and aim to provide context, connections, and alternative perspectives. Explanations should not provide instructions or technical references. Their purpose is to explain and clarify information in a clear, accurate, and comprehensive manner. When writing an explanation, it is important to connect the topic to other relevant information, provide background and context, focus on the topic itself, and discuss alternative solutions or opinions. The language used in explanations should provide reasons, comparisons, and relevant context to help readers understand the topic.
In summary, the Diátaxis Framework provides a structured approach to categorizing and organizing documents with the name 'document' into four types: tutorials, how-to guides, technical references, and explanations. Each type serves different user needs and requires a different approach in its creation. By understanding and applying this framework, the quality and effectiveness of technical documentation can be greatly improved.